---
sidebar_label: Manage Metadata
sidebar_position: 16
description: Manage Metadata with the Hasura schema/Metadata API
keywords:
  - hasura
  - docs
  - schema/Metadata API
  - API reference
  - metadata
toc_max_heading_level: 2
---

# Schema/Metadata API Reference: Manage Metadata (Deprecated)

:::caution Deprecation

In versions `v2.0.0` and above, the schema/Metadata API is deprecated in
favour of the [schema API](/api-reference/schema-api/index.mdx) and the
[Metadata API](/api-reference/metadata-api/index.mdx).

Though for backwards compatibility, the schema/Metadata APIs will
continue to function.

:::

## Introduction

APIs to manage Hasura Metadata which is stored in `hdb_catalog` schema.

## export_metadata {#schema-metadata-export-metadata}

`export_metadata` is used to export the current Metadata from the server as a JSON file.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "export_metadata",
    "args": {}
}
```

Response:

The response JSON will be the Metadata object. The structure of the
Metadata object is just a JSON version of the
[Metadata files](/migrations-metadata-seeds/legacy-configs/config-v2/reference/metadata-format.mdx) generated by the CLI.

## replace_metadata {#schema-metadata-replace-metadata}

`replace_metadata` is used to replace/import Metadata into Hasura.
Existing Metadata will be replaced with the new one.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "replace_metadata",
    "version": 1 | 2 (optional),
    "args": <replace-metadata-args>
}
```

### Args syntax {#schema-metadata-replace-metadata-syntax}

If version is set to 1, then args should be the JSON object which is
same as the output of [export_metadata](#schema-metadata-export-metadata).

For version 2, the following structure is used:

```json
{
    allow_inconsistent_metadata: Boolean,
    metadata: metadata-object
}
```

| Key                         | Required | Schema                                              | Description                                                                                                                           |
| --------------------------- | -------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| allow_inconsistent_metadata | false    | Boolean                                             | If set to `true`, Metadata will be replaced with a warning in the response indicating which items are inconsistent (default: `false`) |
| allow_warnings              | false    | Boolean                                             | If set to `false`, any warnings will cause the metadata API call to fail (default: `true`)                                            |
| metadata                    | true     | [export_metadata](#schema-metadata-export-metadata) | The Metadata that will replace the current metadata.                                                                                  |

If the version is not specified, then it is inferred from the format of `args`.

### Responses

Example with inconsistencies:

```http
HTTP/1.1 400 Bad Request

{
  "internal": [
    {
      "type": "remote_schema",
      "reason": "HTTP exception occurred while sending the request to http://localhost:5000/hello-graphql",
      "definition": {
        "definition": {
          "url": "http://localhost:5000/hello-graphql",
          "forward_client_headers": false
        },
        "name": "test",
        "permissions": [],
        "comment": "testing replace metadata with remote schemas"
      }
    }, ...
  ]
}
```

## reload_metadata {#schema-metadata-reload-metadata}

`reload_metadata` should be used when there is a change in underlying
Postgres database that Hasura should be aware of. Example: a new column
is added to a table using `psql` and this column should now be added to
the GraphQL schema.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "reload_metadata",
    "args": {
        "reload_remote_schemas": true
    }
}
```

Response:

If the Metadata is consistent:

```json
{
  "is_consistent": true,
  "message": "success"
}
```

If the Metadata is not consistent:

```json
{
  "is_consistent": false,
  "message": "success",
  "inconsistent_objects": [
    {
      "definition": {
        "schema": "public",
        "name": "article"
      },
      "name": "table article in source default",
      "reason": "Inconsistent object: no such table/view exists in source: \"article\"",
      "type": "table"
    }
  ]
}
```

### Args syntax {#schema-metadata-reload-metadata-syntax}

| Key                   | Required | Schema                                                                               | Description                                                                                                                |
| --------------------- | -------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| reload_remote_schemas | false    | `Boolean` \| \[[RemoteSchemaName](/api-reference/syntax-defs.mdx#remoteschemaname)\] | If set to `true`, all Remote Schemas' (including inconsistent ones) cached GraphQL schemas are refreshed (default: `true`) |

## clear_metadata {#schema-metadata-clear-metadata}

`clear_metadata` can be used to reset the state of Hasura -- clean the
current state by forgetting the tables tracked, relationships,
permissions, Event Triggers etc.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "clear_metadata",
    "args": {}
}
```

## get_inconsistent_metadata {#schema-metadata-get-inconsistent-metadata}

`get_inconsistent_metadata` can be used to fetch all inconsistent Metadata objects.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "get_inconsistent_metadata",
    "args": {}
}
```

Response:

```json
[
  {
    "definition": {
      "using": {
        "foreign_key_constraint_on": {
          "column": "author_id",
          "table": "article"
        }
      },
      "name": "articles",
      "comment": null,
      "table": "author"
    },
    "reason": "table \"article\" does not exist",
    "type": "array_relation"
  },
  {
    "definition": {
      "using": {
        "foreign_key_constraint_on": "author_id"
      },
      "name": "author",
      "comment": null,
      "table": "article"
    },
    "reason": "table \"article\" does not exist",
    "type": "object_relation"
  },
  {
    "definition": "article",
    "reason": "no such table/view exists in source : \"article\"",
    "type": "table"
  }
]
```

## drop_inconsistent_metadata {#schema-metadata-drop-inconsistent-metadata}

`drop_inconsistent_metadata` can be used to purge all inconsistent
objects from the metadata.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "drop_inconsistent_metadata",
    "args": {}
}
```
